home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / ada / c01lab4.zip / LRMRDR / LRM_CHAP.ZIP / CHAP07.DOC < prev    next >
Text File  |  1992-04-21  |  37KB  |  887 lines
  1. >                                 7. Packages
  2.  
  3.  
  4.  
  5. Packages  are  one of the four forms of program unit, of which programs can
  6. be composed.  The other forms are  subprograms,  task  units,  and  generic
  7. units.
  8.  
  9.  
  10. Packages  allow  the specification of groups of logically related entities.
  11. In their simplest form packages specify pools of  common  object  and  type
  12. declarations.   More  generally,  packages can be used to specify groups of
  13. related entities including also subprograms that can be called from outside
  14. the package, while their inner workings remain concealed and protected from
  15. outside users.
  16.  
  17.  
  18. References:  generic unit 12, program unit 6, subprogram 6,  task  unit  9,
  19. type declaration 3.3.1
  20.  
  21. > 7.1  Package Structure
  22.  
  23.  
  24. A  package is generally provided in two parts:  a package specification and
  25. a package body.  Every package has a package  specification,  but  not  all
  26. packages have a package body.
  27.  
  28.  
  29.     package_declaration ::= package_specification;
  30.  
  31.     package_specification ::=
  32.         package identifier is
  33.           {basic_declarative_item}
  34.        [private
  35.           {basic_declarative_item}]
  36.         end [package_simple_name]
  37.  
  38.     package_body ::=
  39.         package body package_simple_name is
  40.            [declarative_part]
  41.        [begin
  42.             sequence_of_statements
  43.        [exception
  44.             exception_handler
  45.            {exception_handler}]]
  46.         end [package_simple_name];
  47.  
  48.  
  49. The  simple  name  at  the  start of a package body must repeat the package
  50. identifier.  Similarly if a simple name appears at the end of  the  package
  51. specification or body, it must repeat the package identifier.
  52.  
  53.  
  54. If  a subprogram declaration, a package declaration, a task declaration, or
  55. a  generic  declaration  is  a  declarative  item  of   a   given   package
  56. specification, then the body (if there is one) of the program unit declared
  57. by  the  declarative  item  must  itself  be  a  declarative  item  of  the
  58. declarative part of the body of the given package.
  59.  
  60. Notes:
  61.  
  62.  
  63. A simple form of package, specifying a pool of objects and types, does  not
  64. require  a  package  body.   One  of  the  possible uses of the sequence of
  65. statements of a package body is  to  initialize  such  objects.   For  each
  66. subprogram  declaration   there  must be a corresponding body (except for a
  67. subprogram written in another language, as explained in section 13.9).   If
  68. the  body  of  a  program  unit  is a body stub, then a separately compiled
  69. subunit containing the  corresponding  proper  body  is  required  for  the
  70. program  unit  (see  10.2).   A body is not a basic declarative item and so
  71. cannot appear in a package specification.
  72.  
  73.  
  74. A package  declaration  is  either  a  library  package  (see  10.2)  or  a
  75. declarative item declared within another program unit.
  76.  
  77.  
  78. References:   basic  declarative item 3.9, body stub 10.2, declarative item
  79. 3.9, declarative part 3.9,  exception  handler  11.2,  generic  body  12.2,
  80. generic  declaration  12.1,  identifier 2.3, library unit 10.1, object 3.2,
  81. package body 7.3, program unit 6, proper body 3.9, sequence  of  statements
  82. 5.1,  simple  name  4.1,  subprogram  body 6.3, subprogram declaration 6.1,
  83. subunit 10.2, task body 9.1, task declaration 9.1, type 3.3
  84.  
  85. > 7.2  Package Specifications and Declarations
  86.  
  87.  
  88. The first list of declarative items  of  a package specification is  called
  89. the  visible  part  of the package.  The optional list of declarative items
  90. after the reserved word private is called the private part of the  package.
  91.  
  92.  
  93. An  entity declared in the private part of a package is not visible outside
  94. the package itself  (a name denoting such an entity is only possible within
  95. the package).  In contrast, expanded names denoting  entities  declared  in
  96. the visible part can be used even outside the package;  furthermore, direct
  97. visibility  of  such  entities can be achieved by means of use clauses (see
  98. 4.1.3 and 8.4).
  99.  
  100.  
  101. The elaboration of a package declaration consists of the elaboration of its
  102. basic declarative items in the given order.
  103.  
  104. Notes:
  105.  
  106.  
  107. The visible part of a package contains all  the  information  that  another
  108. program  unit  is  able to know about the package.  A package consisting of
  109. only a package specification (that is, without a package body) can be  used
  110. to  represent a group of common constants or variables, or a common pool of
  111. objects and types, as in the examples below.
  112.  
  113.  
  114. Example of a package describing a group of common variables:
  115.  
  116.     package PLOTTING_DATA is
  117.        PEN_UP : BOOLEAN;
  118.        CONVERSION_FACTOR,
  119.        X_OFFSET, Y_OFFSET,
  120.        X_MIN,    Y_MIN,
  121.        X_MAX,    Y_MAX:   REAL;     --  see 3.5.7
  122.  
  123.        X_VALUE : array (1 .. 500) of REAL;
  124.        Y_VALUE : array (1 .. 500) of REAL;
  125.     end PLOTTING_DATA;
  126.  
  127.  
  128. Example of a package describing a common pool of objects and types:
  129.  
  130.     package WORK_DATA is
  131.        type DAY is (MON, TUE, WED, THU, FRI, SAT, SUN);
  132.        type HOURS_SPENT is delta 0.25 range 0.0 .. 24.0;
  133.        type TIME_TABLE  is array (DAY) of HOURS_SPENT;
  134.  
  135.        WORK_HOURS   : TIME_TABLE;
  136.        NORMAL_HOURS : constant TIME_TABLE :=
  137.                          (MON .. THU => 8.25, FRI => 7.0, SAT | SUN => 0.0);
  138.     end WORK_DATA;
  139.  
  140.  
  141. References:  basic declarative item 3.9, constant 3.2.1,  declarative  item
  142. 3.9, direct visibility 8.3, elaboration 3.9, expanded name 4.1.3, name 4.1,
  143. number  declaration  3.2.2,  object  declaration  3.2.1, package 7, package
  144. declaration 7.1, package identifier 7.1, package specification  7.1,  scope
  145. 8.2,  simple  name  4.1,  type  declaration 3.3.1, use clause 8.4, variable
  146. 3.2.1
  147.  
  148. > 7.3  Package Bodies
  149.  
  150.  
  151. In contrast to the entities declared in  the  visible  part  of  a  package
  152. specification,  the  entities declared in the package body are only visible
  153. within the package body itself.  As a consequence, a package with a package
  154. body can be used for the construction of a group of related subprograms  (a
  155. package  in  the usual sense), in which the logical operations available to
  156. the users are clearly isolated from the internal entities.
  157.  
  158.  
  159. For the elaboration of a  package  body,  its  declarative  part  is  first
  160. elaborated,  and its sequence of statements (if any) is then executed.  The
  161. optional  exception  handlers  at  the  end  of  a  package  body   service
  162. exceptions raised during the execution of the sequence of statements of the
  163. package body.
  164.  
  165. Notes:
  166.  
  167.  
  168. A  variable  declared  in the body of a package is only visible within this
  169. body and, consequently, its value can only be changed  within  the  package
  170. body.   In the absence of local tasks, the value of such a variable remains
  171. unchanged between calls issued from  outside  the  package  to  subprograms
  172. declared  in  the  visible  part.   The  properties  of such a variable are
  173. similar to those of an "own" variable of Algol 60.
  174.  
  175.  
  176. The elaboration of the body of a subprogram declared in the visible part of
  177. a package is caused by the elaboration of the body of the package.  Hence a
  178. call of such a subprogram by an outside program unit raises  the  exception
  179. PROGRAM_ERROR if the call takes place before the elaboration of the package
  180. body (see 3.9).
  181.  
  182.  
  183. Example of a package:
  184.  
  185.     package RATIONAL_NUMBERS is
  186.  
  187.        type RATIONAL is
  188.           record
  189.              NUMERATOR   : INTEGER;
  190.              DENOMINATOR : POSITIVE;
  191.           end record;
  192.  
  193.        function EQUAL(X,Y : RATIONAL) return BOOLEAN;
  194.  
  195.        function "/"  (X,Y : INTEGER)  return RATIONAL;  --  to construct a rational number
  196.  
  197.        function "+"  (X,Y : RATIONAL) return RATIONAL;
  198.        function "-"  (X,Y : RATIONAL) return RATIONAL;
  199.        function "*"  (X,Y : RATIONAL) return RATIONAL;
  200.        function "/"  (X,Y : RATIONAL) return RATIONAL;
  201.     end;
  202.  
  203.     package body RATIONAL_NUMBERS is
  204.  
  205.        procedure SAME_DENOMINATOR (X,Y : in out RATIONAL) is
  206.        begin
  207.           --  reduces X and Y to the same denominator:
  208.           ...
  209.        end;
  210.  
  211.        function EQUAL(X,Y : RATIONAL) return BOOLEAN is
  212.           U,V : RATIONAL;
  213.        begin
  214.           U